 /*******************************************************************************
  * Copyright (c) 2000, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui;

 import org.eclipse.jface.action.IAction;
 import org.eclipse.jface.action.IMenuManager;
 import org.eclipse.jface.action.IStatusLineManager;
 import org.eclipse.jface.action.IToolBarManager;
 import org.eclipse.ui.services.IServiceLocator;

 /**
  * Used by a part to access its menu, toolbar, and status line managers.
  * <p>
  * Within the workbench each part, editor or view, has a private set of action
  * bars. This set, which contains a menu, toolbar, and status line, appears
  * in the local toolbar for a view and in the window for an editor. The view
  * may provide an implementation for pre-existing actions or add new actions to
  * the action bars.
  * </p><p>
  * In a workbench window there are a number of actions which are applicable to
  * all parts. Some common examples are <code>CUT</code>, <code>COPY</code> and
  * <code>PASTE</code>. These actions, known as "global actions", are contributed to
  * the workbench window by the window itself and shared by all parts. The
  * presentation is owned by the window. The implementation is delegated to the
  * active part.
  * </p><p>
  * To participate in the global action design an <code>IWorkbenchPart</code> should
  * register a handler for each global action which is implemented by the part. This
  * can be done by calling <code>setGlobalActionHandler</code>. For convenience, the
  * standard global actions are defined in
  * <code>org.eclipse.ui.IWorkbenchActionConstants</code>.
  * </p><p>
  * Additional work is required for the <code>Delete</code> global action. In
  * this case the accelerator is defined in the menu item text but is not hooked
  * on the window. This is to support text editors where the <code>Delete</code>
  * key is functional even when the <code>Delete</code> action is disabled (no text
  * is selected). An implementation for this accelerator must be defined locally,
  * in each part, by listening for <code>Delete</code> key events.
  * </p><p>
  * A part may also contribute new actions to the action bars as required. To do
  * this, call <code>getMenuManager</code>, <code>getToolBarManager</code>, or
  * <code>getStatusLineManager</code> as appropriate to get the action target.
  * Add the action(s) to the target and call <code>update</code> to commit
  * any changes to the underlying widgets.
  * </p><p>
  * This interface is not intended to be implemented by clients.
  * </p>
  */
 public interface IActionBars {
     /**
      * Clears the global action handler list.
      * <p>
      * Note: Clients who manipulate the global action list are
      * responsible for calling <code>updateActionBars</code> so that the changes
      * can be propagated throughout the workbench.
      * </p>
      */
     public void clearGlobalActionHandlers();

     /**
      * Returns the global action handler for the action with the given id.
      *
      * @param actionId an action id declared in the registry
      * @return an action handler which implements the action id, or
      * <code>null</code> if none is registered
      * @see IWorkbenchActionConstants
      * @see #setGlobalActionHandler(String, IAction)
      */
     public IAction getGlobalActionHandler(String actionId);

     /**
      * Returns the menu manager.
      * <p>
      * Note: Clients who add or remove items from the returned menu manager are
      * responsible for calling <code>updateActionBars</code> so that the changes
      * can be propagated throughout the workbench.
      * </p>
      *
      * @return the menu manager
      */
     public IMenuManager getMenuManager();
     
     /**
      * Returns the service locator for these action bars. The locator is found
      * by looking locally, and then ascending the action bar hierarchy.
      *
      * @return The service locator; never <code>null</code>.
      * @since 3.2
      */
     public IServiceLocator getServiceLocator();

     /**
      * Returns the status line manager.
      * <p>
      * Note: Clients who add or remove items from the returned status line
      * manager are responsible for calling <code>updateActionBars</code> so
      * that the changes can be propagated throughout the workbench.
      * </p>
      *
      * @return the status line manager
      */
     public IStatusLineManager getStatusLineManager();

     /**
      * Returns the tool bar manager.
      * <p>
      * Note: Clients who add or remove items from the returned tool bar manager are
      * responsible for calling <code>updateActionBars</code> so that the changes
      * can be propagated throughout the workbench.
      * </p>
      *
      * @return the tool bar manager
      */
     public IToolBarManager getToolBarManager();

     /**
      * Sets the global action handler for the action with the given id.
      * <p>
      * Note: Clients who manipulate the global action list are
      * responsible for calling <code>updateActionBars</code> so that the changes
      * can be propagated throughout the workbench.
      * </p>
      *
      * @param actionId an action id declared in the registry
      * @param handler an action which implements the action id, or
      * <code>null</code> to clear any existing handler
      * @see IWorkbenchActionConstants
      */
     public void setGlobalActionHandler(String actionId, IAction handler);

     /**
      * Updates the action bars.
      * <p>
      * Clients who add or remove items from the menu, tool bar, or status line
      * managers should call this method to propagated the changes throughout
      * the workbench.
      * </p>
      */
     public void updateActionBars();
 }

